Add overview and basic usage to README by alexander-yevsyukov · Pull Request #76 · SpineEventEngine/compiler

alexander-yevsyukov · 2026-06-27T21:25:58Z

Summary

Replaces the placeholder README.md — which only said the project was "under
development right now. Proceed with caution." — with production-grade
documentation for the Compiler's v2.0.0 API.

New content:

Overview — what the Compiler is and where it fits in the Spine SDK.
How it works — the reactive pipeline: protoc → code-generation request →
events → views/policies → renderers.
Getting started — requirements (JDK 17, the Protobuf Gradle Plugin) and
applying the io.spine.compiler Gradle plugin.
Configure code-generation plugins — the spine { compiler { plugins(…) } }
DSL and the spineCompiler classpath configuration.
Writing a plugin — a minimal Renderer/Plugin example and the
io.spine.tools:compiler-api coordinate.
Modules, Further reading, and License sections.

The plugin ID, DSL shape, API identifiers (Plugin, Renderer, SourceFileSet),
artifact coordinates, and the JDK version were all verified against the sources
(api/, gradle-api/, gradle-plugin/, buildSrc/) rather than assumed. Version
references in the snippets use a <Compiler version> placeholder.

Closes #72.

README rename consolidated from another branch

The Spine Compiler rename and current-API refresh of the secondary READMEs was
done on a separate branch — claude/ecstatic-ride-7f0e7c, commit dfec572c7b
("Update READMEs for the Spine Compiler rename and current API") — and folded
into this PR via cherry-pick (f21d34dd02), so the related documentation lands
in a single review instead of a second PR:

tests/README.md — "ProtoData" → "Spine Compiler" naming for the
integration-test project, plus a typo fix.
gradle-plugin/README.md — rewritten for the current API: the
spine { compiler { } } DSL, the configuration table (plugins, subDirs,
outputBaseDir), source-set task naming (launch…SpineCompiler), and the
Protobuf Gradle Plugin requirement.

Dependency refresh

Refreshes the CoreJvm Spine dependency (spine-core / spine-client /
spine-server) from 2.0.0-SNAPSHOT.380 to .381, the latest published
snapshot.

Version & dependency reports

Per the repository version policy, this branch bumps version.gradle.kts
2.0.0-SNAPSHOT.056 → .057 and regenerates the dependency reports
(docs/dependencies/pom.xml, docs/dependencies/dependencies.md) so the
License Reports check passes.

Verification

review-docs and spine-code-review: APPROVE — no findings.
./gradlew build -x integrationTest: BUILD SUCCESSFUL, including with the
CoreJvm bump. integrationTest is excluded locally — it exercises the
consumer composite build (unaffected by docs/version/dependency-refresh
changes) and this checkout has a broken tests/ symlink; CI runs the full
suite.

🤖 Generated with Claude Code

Replace the placeholder "under development" note with production-grade documentation: a project overview, a "How it works" pipeline summary, Gradle plugin setup, a plugin-authoring example, a modules table, and reference links. Closes #72. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Copilot

Pull request overview

Updates the project’s public-facing documentation to describe Spine Compiler’s intended v2.0.0 API and basic Gradle usage, and bumps the snapshot version + regenerated dependency reports to keep license reporting consistent.

Changes:

Replace the placeholder README.md with overview, workflow explanation, Gradle setup, and plugin authoring guidance.
Bump compilerVersion snapshot (.056 → .057) and propagate it into generated dependency report artifacts.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
`README.md`	Adds production-grade overview and usage docs (Gradle plugin setup, DSL configuration, plugin authoring).
`version.gradle.kts`	Increments the project snapshot version used for publishing/tests.
`docs/dependencies/pom.xml`	Updates generated dependency-report POM version to match the bumped snapshot.
`docs/dependencies/dependencies.md`	Updates generated dependency report headers/timestamps for the bumped snapshot.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ddbe26442e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Apply the `java` plugin instead of `kotlin("jvm")` in the Getting started example so Java-only projects are not implied to require Kotlin, and note that either language works. Clarify that the `compiler { }` DSL block is nested inside the `spine { }` extension. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Rename ProtoData references to Spine Compiler in `tests/README.md` and `gradle-plugin/README.md`. Identifiers are verified against the source: the `compiler { }` extension, the `spineCompiler` configuration, the `LaunchSpineCompiler` task type, and the `io.spine.compiler` plugin id. Also bring `gradle-plugin/README.md` back in line with the current API: - use the real `Plugin` package `io.spine.tools.compiler.plugin.Plugin`; - document the real DSL options (`plugins`, `subDirs`, `outputBaseDir`) via the `spine { compiler { } }` block, dropping options that no longer exist; - fix the Maven coordinates to `io.spine.tools:compiler-gradle-plugin` and `io.spine.tools:compiler-api`. Fix a typo in `tests/README.md` and minor prose issues. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The Compiler does not auto-apply the Protobuf Gradle Plugin; `Plugin.kt` fails fast when `com.google.protobuf` is absent. Restore `id("com.google.protobuf")` in the plugins block and state the requirement, matching `gradle-plugin/README.md` and the code. Also drops a stray `.:` typo. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Replace the unresolved `$version` reference (and the not-yet-published `2.0.0`) in the Getting started and plugin-authoring snippets with the `<Compiler version>` placeholder, matching `gradle-plugin/README.md`. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The per-module breakdown is architecture detail, not user-facing documentation, so the `## Modules` section is dropped from `README.md`. `docs/project.md` already lists every module; this folds the README's unique detail — the `compiler-` artifact prefix and the `io.spine.compiler` plugin ID — into that doc's Architecture section. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Address PR review: add the required Protobuf Gradle Plugin (with a `<Protobuf plugin version>` placeholder) to the `plugins {}` examples in both READMEs so they work when copied, and replace the undefined `moon.phase` example in `gradle-plugin/README.md` with a comment. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

codecov · 2026-06-27T23:14:43Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 75.60%. Comparing base (dbeda81) to head (89c1035).

Additional details and impacted files

@@            Coverage Diff            @@
##             master      #76   +/-   ##
=========================================
  Coverage     75.60%   75.60%           
  Complexity      677      677           
=========================================
  Files           203      203           
  Lines          3947     3947           
  Branches        390      390           
=========================================
  Hits           2984     2984           
  Misses          845      845           
  Partials        118      118

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

alexander-yevsyukov and others added 3 commits June 27, 2026 21:58

Bump version -> 2.0.0-SNAPSHOT.057

66d09fb

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Update dependency reports

ddbe264

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Copilot AI review requested due to automatic review settings June 27, 2026 21:25

Copilot started reviewing on behalf of alexander-yevsyukov June 27, 2026 21:26 View session

Copilot AI reviewed Jun 27, 2026

View reviewed changes

Comment thread README.md

Comment thread README.md Outdated

chatgpt-codex-connector Bot reviewed Jun 27, 2026

View reviewed changes

Comment thread README.md Outdated

alexander-yevsyukov self-assigned this Jun 27, 2026

alexander-yevsyukov added this to v2.0 Jun 27, 2026

alexander-yevsyukov moved this to 🏗 In progress in v2.0 Jun 27, 2026

alexander-yevsyukov and others added 5 commits June 27, 2026 23:08

Bump CoreJvm

9d23beb

Improve README wording around Protobuf Gradle Plugin

597996a

Update dependency reports

ef40ed4

Copilot AI review requested due to automatic review settings June 27, 2026 22:17

Copilot started reviewing on behalf of alexander-yevsyukov June 27, 2026 22:18 View session

Copilot AI reviewed Jun 27, 2026

View reviewed changes

Comment thread README.md

alexander-yevsyukov and others added 2 commits June 27, 2026 23:24

Copilot AI review requested due to automatic review settings June 27, 2026 22:34

Copilot started reviewing on behalf of alexander-yevsyukov June 27, 2026 22:35 View session

Copilot AI reviewed Jun 27, 2026

View reviewed changes

Comment thread README.md Outdated

Comment thread gradle-plugin/README.md

Comment thread gradle-plugin/README.md Outdated

alexander-yevsyukov requested a review from armiol June 27, 2026 23:20

armiol approved these changes Jun 28, 2026

View reviewed changes

alexander-yevsyukov merged commit 040ec9e into master Jun 28, 2026
11 checks passed

alexander-yevsyukov deleted the update-readme-overview-usage branch June 28, 2026 15:21

github-project-automation Bot moved this from 🏗 In progress to ✅ Done in v2.0 Jun 28, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add overview and basic usage to README#76

Add overview and basic usage to README#76
alexander-yevsyukov merged 12 commits into
masterfrom
update-readme-overview-usage

alexander-yevsyukov commented Jun 27, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Jun 27, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

alexander-yevsyukov commented Jun 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

README rename consolidated from another branch

Dependency refresh

Version & dependency reports

Verification

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Jun 27, 2026

Codecov Report

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

alexander-yevsyukov commented Jun 27, 2026 •

edited

Loading